The FindFile OSAX scripting addition is a collection of functions that allows you to gather lists of files and folders starting at any location on any drive connected to your Macintosh, including items in subfolders, no matter how deep. It is written in CodeWarrior and is extremely fast. You can search for files with criteria just like you would in the Mac OS Find File utility. If you want to cancel the search mid-stream, just press the command-period key combination, and FindFile will halt the search and return you to your scripting. All of this power is available to you from within your AppleScripts, with the ease and simplicity of the english language.
Sounds Great! How Do I Use It?
This scripting addition follows easy-to-understand english calling conventions as you will see below. It is a breeze to use the FindFile scripting addition in your scripts.
This scripting addition responds to two commands: FindFile, and MatchInList. The commands are explained in detail below.
Upon return, this variable contains a list of file specifications. The list will either be a list of files, folders, or both, depending on what parameters you supply to the FindFile function. Only those items matching the criteria you specify are listed.
starting_at startHere
This is a required parameter - you must supply a starting location for the scan. It is expected to be an alias, file specification, or full path of the file or folder where the scan is to begin. Full paths must resolve to an existing file or folder.
name_contains string
name_starts_with string
name_ends_with string
name_is string
name_is_not string
name_does_not contain string
This parameter is a string where you may supply a file name which FindFile will use to determine which files will be included in your list. This string is not case sensitive. You can think of this parameter as being the same as the filename field in the Mac OS Find File / Sherlockwindow. If you do not supply this parameter, filenames will be ignored during the search.
filesize_is Integer
filesize_is_not Integer
This parameter is expected to be an integer where you may supply a number in the range of 0 to 4,294,967,295 representing a number of bytes. Depending on which parameter you use, FindFile will return only files less than or greater than this size. If you do not supply this parameter, files of any size will be included in the list. This parameter has no effect on folders.
filetype_is typeList
filetype_is_not typeList
This parameter is a list where you may supply up to 64 file types (4-character OSTypes) which FindFile will use to determine which files will be included in your list. The list you supply should either take on the form: {"TEXT","PICT"}, or "TEXTPICT". If you do not supply this parameter, files of any type will be included in the list. This parameter has no effect on folders.
creator_is typeList
creator_is_not typeList
This parameter is a list where you may supply up to 64 creator types (4-character OSTypes) which FindFile will use to determine which files will be included in your list. The list you supply should either take on the form: {"CWIE","8BIM"}, or "CWIE8BIM". If you do not supply this parameter, files of any creator will be included in the list. This parameter has no effect on folders.
label_is label
label_is_not label
This parameter is expected to be a string or a number. If you supply a string, a label matching the string will be looked for. If a matching label is found, any files with that label will be added to the list. If you supply a number, then any file with the corresponding label will be included in the list. See the picture below for a list of the label numbers. You may of course change your label text in the Finder and search for the changed text in your scripts. The numbers however will always remain the same. If you do not supply this parameter, files with any label will be included in the list. This option affects both files and folders.
kind_is_alias kind_is_not_alias
kind_is_application kind_is_not_application
kind_is_clipping kind_is_not_clipping
kind_is_control_panel kind_is_not_control_panel
kind_is_document kind_is_not_document *** NOT OPERATIONAL ***
kind_is_extension kind_is_not_extension
kind_is_font kind_is_not_font
kind_is_letter kind_is_not_letter
kind_is_sound kind_is_not_sound
kind_is_stationery kind_is_not_stationery
This parameter lets you request certain kinds of files to be returned by FindFile. If you do not supply this parameter, files of any kind will be included in the list. This parameter has no effect on folders.
date_created_is date_modified_is
date_created_is_not date_modified_is_not
date_created_is_before date_modified_is_before
date_created_is_after date_modified_is_after
This parameter lets you instruct FindFile to only include files created or modified within the date range specified. The date you supply must resolve to a date object as shown below.
set date1 to current date
set date2 to date "1/22/99"
If you do not supply this parameter, files with any creation / modification date will be included in the list. This parameter works on folders as well as files.
result_type type
Use this parameter to define the type of items you want FindFile to return in the list of files that match your criteria. Result types currently supported are:
“text” - FindFile will return a list of file names that match your criteria
“TEXT” - FindFile will return a list of filepaths that match your criteria
“fss “ - FindFile will return a list of file specifications that match your search criteria
“alis“ - FindFile will return a list of aliases that match your search criteria
More types may be added in the future. This parameter replaces the names_only parameter.
with subfolders
This optional parameter tells FindFile to include contents of subfolders in its scan. If the folder pointed to by the starting_at parameter contains subfolders and this option is included in your call to FindFile, the resulting list will contain all items in those subfolders. If this option is left out of the call to FindFile, the resulting list will not include contents of subfolders.
with display
This optional parameter tells FindFile to show it's status display while performing the scan. The status display shows information about each file being examined by the osax in real-time:
with files
with folders
These optional parameters tell FindFile which items you want listed (folders, files, or both). If you do not supply either of these parameters, FindFile defaults to listing files only.
with results
This optional parameter tells FindFile to show the results of a scan after the scan is complete. Elapsed time and number of files searched / found are reported.
with events
This optional parameter tells FindFile to allow other applications to process events during a scan. Be warned that turning this feature on will slow the scan down.
MatchInList
set idx to MatchInList theList name_contains string
idx
Upon return, this variable contains an integer representing the index of the first occurance of an item that matches your search criteria in the list you specified.
theList
This parameter is required. It is expected to be the list returned by the FindFile command described above. MatchInList will search through this list in a speedy manner looking for items matching your criteria.
name_contains string
name starts with string
name ends with string
name is string
name is not string
name does not contain string
This parameter is a string where you may supply a file name which FindFile will use to determine which files will be included in your list. This string is not case sensitive. You can think of this parameter as being the same as the filename field in the Mac OS Find File / Sherlockwindow. If you do not supply this parameter, filenames will be ignored during the search.
This software is offered with no guarantee of support whatsoever (unless freely and unexpectedly given, purely out of the grace and excellent basic goodness-of-heart of said author, who makes absolutely no claims whatsoever to promise same). Nevertheless, and with all serious intentions of being a "fine person of some reasonable degree of earnestness, kind-hearted interest, human understanding and worthwhile character," said author would like to hear from you concerning your excellent or other adventures or misadventures with this software.
This software may be distributed with the following requirements:
A) Documentation/text files, copyright notices, contact information, and installer must remain intact and unchanged and be distributed as a whole.
B) Persons or organizations wishing to distribute this software must obtain permission from David Blache, Microcosm Software before doing so.
The FindFile OSAX is shareware. If you find yourself using this software after 30 days of installing it, we ask that you send $15.00 US to the following address:
Make checks payable to: David Blache
Microcosm Software
11511 Metric Blvd.
Suite 928
Austin, TX 78758
Web: http://www.thesanctuary.com/microcosm/
Email: alterego@austin.rr.com
Suggestions?
If you have any suggestions for improvement to this scripting addition, feel free to write me at alterego@austin.rr.com. I am always looking for a better way to do things, and I promise to be open to all suggestions. If you encounter problems using this software, please let me know! It is important to me that my software be compatible and as bug-free as possible! Thanks for your interest in my product. I hope you enjoy using it as much as I enjoy developing it.
